<!--
  ****************************************************************************
  * Copyright 2018-2024,2025 Thomas E. Dickey                                *
  * Copyright 2002-2012,2017 Free Software Foundation, Inc.                  *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
  * "Software"), to deal in the Software without restriction, including      *
  * without limitation the rights to use, copy, modify, merge, publish,      *
  * distribute, distribute with modifications, sublicense, and/or sell       *
  * copies of the Software, and to permit persons to whom the Software is    *
  * furnished to do so, subject to the following conditions:                 *
  *                                                                          *
  * The above copyright notice and this permission notice shall be included  *
  * in all copies or substantial portions of the Software.                   *
  *                                                                          *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  *                                                                          *
  * Except as contained in this notice, the name(s) of the above copyright   *
  * holders shall not be used in advertising or otherwise to promote the     *
  * sale, use or other dealings in this Software without prior written       *
  * authorization.                                                           *
  ****************************************************************************
  * @Id: curs_get_wstr.3x,v 1.70 2025/02/15 14:55:47 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>curs_get_wstr 3x 2025-02-15 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">

</HEAD>
<BODY>
<H1 class="no-header">curs_get_wstr 3x 2025-02-15 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>                Library calls               <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>




</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
       <STRONG>get_wstr</STRONG>,  <STRONG>getn_wstr</STRONG>,  <STRONG>wget_wstr</STRONG>,  <STRONG>wgetn_wstr</STRONG>, <STRONG>mvget_wstr</STRONG>, <STRONG>mvgetn_wstr</STRONG>,
       <STRONG>mvwget_wstr</STRONG>, <STRONG>mvwgetn_wstr</STRONG> - read a wide-character string from a  <EM>curses</EM>
       terminal keyboard


</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>

       <STRONG>int</STRONG> <STRONG>get_wstr(wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>wget_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>mvget_wstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>mvwget_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG>

       <STRONG>int</STRONG> <STRONG>getn_wstr(wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>wgetn_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>mvgetn_wstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>mvwgetn_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG>
             <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG>


</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
       <STRONG>wget_wstr</STRONG>  populates  a user-supplied wide-character string buffer <EM>wstr</EM>
       by repeatedly calling <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> with the <EM>win</EM> argument until  a  line
       feed or carriage return character is input.  The function

       <STRONG>o</STRONG>   does not copy the terminating character to <EM>wstr</EM>;

       <STRONG>o</STRONG>   populates  <EM>wstr</EM> with <EM>WEOF</EM> (as defined in <EM>wchar.h</EM>) if an end-of-file
           condition occurs on the input;

       <STRONG>o</STRONG>   always terminates the string with a null wide character (after  any
           <EM>WEOF</EM>);

       <STRONG>o</STRONG>   interprets   the   screen's   erase   and   kill   characters  (see
           <STRONG><A HREF="curs_termattrs.3x.html">erasewchar(3x)</A></STRONG> and <STRONG><A HREF="curs_termattrs.3x.html">killwchar(3x)</A></STRONG>);

       <STRONG>o</STRONG>   recognizes function keys only if  the  screen's  keypad  option  is
           enabled (see <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG>);

       <STRONG>o</STRONG>   treats the function keys <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> the same as the
           erase character; and

       <STRONG>o</STRONG>   discards function key inputs other than those treated as the  erase
           character, calling <STRONG><A HREF="curs_beep.3x.html">beep(3x)</A></STRONG>.

       The  erase  character  replaces  the character at the end of the buffer
       with a null wide character, while the kill character does the same  for
       the entire buffer.

       If  the  screen's  echo  option  is  enabled  (see <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG>), <STRONG>wget_wstr</STRONG>
       updates <EM>win</EM> with <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>.  Further,

       <STRONG>o</STRONG>   the erase character and its function key synonyms move  the  cursor
           to the left, and

       <STRONG>o</STRONG>   the  kill character returns the cursor to where it was located when
           <STRONG>wget_wstr</STRONG> was called.

       <STRONG>wgetn_wstr</STRONG> is similar, but reads at most <EM>n</EM> wide characters, aiding  the
       application  to  avoid overrunning the buffer to which <EM>wstr</EM> points.  An
       attempt  to  input  more  than  <EM>n</EM>  wide  characters  (other  than   the
       terminating line feed or carriage return) is ignored with a beep.  If <EM>n</EM>
       is negative, <STRONG>wgetn_wstr</STRONG> reads  up  to  <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM>  wide  characters  (see
       <STRONG>sysconf(3)</STRONG>).

       <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions.


</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
       These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure.

       In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if

       <STRONG>o</STRONG>   <EM>win</EM> is <EM>NULL</EM>, or

       <STRONG>o</STRONG>   if an internal <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> call fails.

       Functions  prefixed with "mv" first perform cursor movement and fail if
       the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries.


</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
       All of these functions except <STRONG>wgetn_wstr</STRONG> may be implemented as macros.

       Reading input that overruns  the  buffer  pointed  to  by  <EM>wstr</EM>  causes
       undefined   results.    Use   the  <STRONG>n</STRONG>-infixed  functions,  and  allocate
       sufficient storage for <EM>wstr</EM> -- at least <EM>n</EM>+1 times <STRONG>sizeof(wchar_t)</STRONG>.

       These functions cannot store a <STRONG>KEY_</STRONG> value in <EM>wstr</EM> because there  is  no
       way to distinguish it from a valid <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> value.

       While  these  functions  conceptually  implement  a  series of calls to
       <STRONG>wget_wch</STRONG>, they also temporarily change properties of the <EM>curses</EM>  screen
       to  permit simple editing of the input buffer.  Each function saves the
       screen's state, calls <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG>, and,  if  the  screen  was  in  canonical
       ("cooked")  mode,  <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG>.  Before returning, it restores the saved
       screen state.  Other implementations differ in detail, affecting  which
       control   characters  they  can  accept  in  the  buffer;  see  section
       "PORTABILITY" below.

       Unlike <STRONG><A HREF="curs_getstr.3x.html">getstr(3x)</A></STRONG> and related  functions  of  <EM>ncurses</EM>'s  non-wide  API,
       these functions do not return <STRONG>KEY_RESIZE</STRONG> if a <EM>SIGWINCH</EM> event interrupts
       the function.


</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
       <STRONG>getn_wstr</STRONG>,  <STRONG>wgetn_wstr</STRONG>,  <STRONG>mvgetn_wstr</STRONG>,  and  <STRONG>mvwgetn_wstr</STRONG>'s  handing  of
       negative <EM>n</EM> values is an <EM>ncurses</EM> extension.


</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
       Applications employing <EM>ncurses</EM> extensions should condition their use on
       the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro.

       X/Open Curses Issue 4 describes these functions.  It specifies no error
       conditions for them.

       Issue 4  documented these functions as passing an array of <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>, but
       that was an error, conflicting  with  the  following  language  in  the
       standard.

              The  effect  of  <EM>get</EM><STRONG>_</STRONG><EM>wstr</EM>()  is  as  though a series of calls to
              <EM>get</EM><STRONG>_</STRONG><EM>wch</EM>() were made,  until  a  newline  character,  end-of-line
              character, or end-of-file character is processed.

       <EM>get</EM><STRONG>_</STRONG><EM>wch</EM>  can  return a negative value (<EM>WEOF</EM>), but <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> is a unsigned
       type.  All of the  vendors  implement  these  functions  using  <EM>wint</EM><STRONG>_</STRONG><EM>t</EM>,
       following the Issue 7 standard.

       X/Open  Curses  Issue 7  is  unclear  whether the terminating null wide
       character counts toward  the  length  parameter  <EM>n</EM>.   A  similar  issue
       affected   <EM>wgetnstr</EM>   in   Issue 4,  Version 2;  Issue 7  revised  that
       function's  description  to  address  the  issue,  but  not   that   of
       <EM>wget</EM><STRONG>_</STRONG><EM>nwstr</EM>, leaving it ambiguous.  <EM>ncurses</EM> counts the terminator in the
       length.

       X/Open Curses does  not  specify  what  happens  if  the  length  <EM>n</EM>  is
       negative.

       <STRONG>o</STRONG>   For  consistency  with  <EM>wgetnstr</EM>, <EM>ncurses</EM> 6.2 uses a limit based on
           <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM>.

       <STRONG>o</STRONG>   Some other implementations (such as Solaris <EM>xcurses</EM>) do  the  same,
           while others (<EM>PDCurses</EM>) do not permit a negative <EM>n</EM>.

       <STRONG>o</STRONG>   NetBSD 7  <EM>curses</EM>  imitates  <EM>ncurses</EM>  6.1  and  earlier,  treating a
           negative <EM>n</EM> as an unbounded count of wide characters.

       Implementations vary in their handling of input control characters.

       <STRONG>o</STRONG>   While they may enable the screen's echo option, some do not take it
           out  of  raw  mode,  and  may  take  cbreak  mode into account when
           deciding whether to handle echoing within <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> or to rely  on
           it as a side effect of calling <EM>wget</EM><STRONG>_</STRONG><EM>wch</EM>.

           Since  1995,  <EM>ncurses</EM> has provided handlers for <EM>SIGINTR</EM> and <EM>SIGQUIT</EM>
           events, which are typically generated at the keyboard with  <STRONG>^C</STRONG>  and
           <STRONG>^\</STRONG> respectively.  In cbreak mode, those handlers catch a signal and
           stop  the  program,  whereas  other  implementations  write   those
           characters into the buffer.

       <STRONG>o</STRONG>   Starting  with <EM>ncurses</EM> 6.3 (2021), <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> preserves raw mode if
           the screen was already in that state, allowing  one  to  enter  the
           characters  the  terminal  interprets  as interrupt and quit events
           into the buffer, for consistency with SVr4 <EM>curses</EM>'s <EM>wgetnstr</EM>.


</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
       X/Open Curses Issue 4 (1995) initially specified these functions.   The
       System V  Interface  Definition  Version 4  of  the same year specified
       functions named <EM>wgetwstr</EM> and <EM>wgetnwstr</EM> (and the usual variants).  These
       were later additions to SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989).
       Except in name, their declarations did not differ from  X/Open's  later
       <EM>wget</EM><STRONG>_</STRONG><EM>wstr</EM>  and <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> until X/Open Curses Issue 7 (2009) eventually
       changed the type of the buffer argument to a pointer to <EM>wint</EM><STRONG>_</STRONG><EM>t</EM>.


</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
       <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> describes comparable functions of the  <EM>ncurses</EM>  library
       in its non-wide-character configuration.

       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>



ncurses 6.5                       2025-02-15                 <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
